8.3 Random Numbers

This package also provides an implementation of the Common Lisp random number generator. It uses its own additive-congruential algorithm, which is much more likely to give statistically clean random numbers than the simple generators supplied by many operating systems.

Function: cl-random number &optional state

This function returns a random nonnegative number less than number, and of the same type (either integer or floating-point). The state argument should be a random-state object that holds the state of the random number generator. The function modifies this state object as a side effect. If state is omitted, it defaults to the internal variable cl--random-state, which contains a pre-initialized default random-state object. (Since any number of programs in the Emacs process may be accessing cl--random-state in interleaved fashion, the sequence generated from this will be irreproducible for all intents and purposes.)

Function: cl-make-random-state &optional state

This function creates or copies a random-state object. If state is omitted or nil, it returns a new copy of cl--random-state. This is a copy in the sense that future sequences of calls to (cl-random n) and (cl-random n s) (where s is the new random-state object) will return identical sequences of random numbers.

If state is a random-state object, this function returns a copy of that object. If state is t, this function returns a new random-state object seeded from the date and time. As an extension to Common Lisp, state may also be an integer in which case the new object is seeded from that integer; each different integer seed will result in a completely different sequence of random numbers.

It is valid to print a random-state object to a buffer or file and later read it back with read. If a program wishes to use a sequence of pseudo-random numbers which can be reproduced later for debugging, it can call (cl-make-random-state t) to get a new sequence, then print this sequence to a file. When the program is later rerun, it can read the original run’s random-state from the file.

Function: cl-random-state-p object

This predicate returns t if object is a random-state object, or nil otherwise.